# 镜像构建

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 源码编译与镜像打包

## Docker 一键构建 M1 Debian 固件 （推荐）

压缩包解到 `docker_env/` 后，会包含 Docker 镜像、运行脚本和默认构建脚本。当前目录中关键文件如下：

| **文件** | **作用** |
| --- | --- |
| `docker_env/docker_builder.tar` | 原始归档包，内含 Docker 镜像和脚本 |
| `docker_env/image.tar.gz` | Docker 镜像包，脚本会加载为 `quecpi-m1l1-builder-ubuntu22:latest` |
| `docker_env/docker_run.sh` | 一键运行入口，默认在容器内执行 `./docker_env/build.sh` |
| `docker_env/build.sh` | 默认构建脚本：执行 `buildconfig`、`buildall`、`buildpackage` |

使用方式如下：

```bash
cd ~/sdk/docker_env

# 如果只拿到 docker_builder.tar，先解包：
tar -xf docker_builder.tar

# 如果该 SDK 目录之前在主机环境直接编译过，切换到 Docker 前先清理旧 TMPDIR：
rm -rf ../build-qti-distro-fullstack-debug/tmp-glibc

# 执行默认一键构建：
./docker_run.sh
```

`docker_run.sh` 的默认行为：

- 若 `../downloads/downloads` 不存在，会从 `3in1_downloads_rl` 克隆并解压 downloads 包。

- 容器以 `--privileged`、`--net host` 启动，并把 SDK 根目录挂载到容器内。

- 默认执行 `./docker_env/build.sh`；也可以给 `docker_run.sh` 传入自定义命令作为容器内任务。

默认 `build.sh` 当前内容如下，目标是 M1 Debian 版本：

```bash
source quectel_build/compile/build.sh
buildconfig \
  QSM200UPEMPI \
  QSM200UEMPIRL1A01_BDL01BP01K0M01V01_LP5.15.153.01.001_V00 \
  DEB || true
buildall
buildpackage
```

脚本成功走完时，终端末尾应能看到 `buildpackage` 阶段的成功信息，包括 QFIL 包解包成功和 debugimg 拷贝完成：

```plaintext
build full qfil success >>>>>>>>>>>>>>>>>>>>>>
UnPacking SUCCESS
TARGET_DEBUG_IMG_DIR: .../quectel_build/fw/QSM200UEMPIRL1A01_BDL01BP01K0M01V01_LP5.15.153.01.001_V00_debugimg
=============== debugimg copy done ===============
[date] finish
```

成功后，固件会输出到 `quectel_build/fw/` 下，以 `ProjectRev` 为前缀，常见目录如下：

| **目录** | **用途** |
| --- | --- |
| `QSM200UEMPIRL1A01_BDL01BP01K0M01V01_LP5.15.153.01.001_V00` | M1 Debian QFIL 完整烧录包 |
| `QSM200UEMPIRL1A01_BDL01BP01K0M01V01_LP5.15.153.01.001_V00_ota` | OTA 包，包含 `full_update_ext4.zip` 和 `target-files-ext4.zip` |
| `QSM200UEMPIRL1A01_BDL01BP01K0M01V01_LP5.15.153.01.001_V00_debug` | 调试符号目录，主要保存 `elf` 文件 |
| `QSM200UEMPIRL1A01_BDL01BP01K0M01V01_LP5.15.153.01.001_V00_debugimg` | 调试镜像目录，包含 `boot.img`、`dtbo.img`、`system.img` 等 |

Docker 和主机直接编译不要混用同一个旧 `tmp-glibc`。如果先在主机编译过，再切到 Docker，BitBake 可能报：

```plaintext
Error, TMPDIR has changed location. You need to either move it back to
/home/soren/QuecPi/SC200/Linux_BL01_R010/build-qti-distro-fullstack-debug/tmp-glibc
or delete it and rebuild
```

这是因为 Docker 内 SDK 路径是 `/home/q1000/Linux_BL01_R010`，而旧的 Yocto `TMPDIR` 记录的是宿主机路径 `/home/soren/...`。如果确定要用 Docker 编译，删除旧的 `build-qti-distro-fullstack-debug/tmp-glibc` 后重新执行 `./docker_run.sh` 即可。下次如果改回主机直接编译，同理让主机重新生成自己的 `tmp-glibc`，不要沿用 Docker 路径下的构建缓存。

# 平台选择与差异对比

当前工程通过 `quectel_build/compile/build.sh` 统一加载构建命令，执行 `buildconfig` 时会按 `ProjectName` 分流到 QSM200U 或 QSM200E 平台。两边的项目名、芯片、MACHINE、Boot 平台和打包产物存在差异，改文档或改代码前建议先对照下表。

| **平台线** | **有效 ProjectName** |
| --- | --- |
| **M1 / QSM200U** | `QSM200UPEMPI`、`QSM200UPNAPI`、`QSM200UPWFPI` |
| **L1 / QSM200E** | `QSM200EPEMPI`、`QSM200EPNAPI`、`QSM200EPWFPI` |

两平台当前可选 `CUST_NAME` 一致：`STD`、`STD_PERF`、`DBG`、`DEB`、`DEB_PERF`。带 `_PERF` 的配置会选择 `qti-distro-fullstack-perf`，其它常规配置默认选择 `qti-distro-fullstack-debug`。

# 初始化构建环境

**步骤一：** 代码下载完成后，进入当前 SDK 根目录执行编译环境脚本：

```bash
cd ~/sdk
source quectel_build/compile/build.sh
```

执行后会加载 `buildconfig`、`buildall`、`buildpackage` 等命令，并打印当前支持的项目名和客户类型。

```plaintext
Vaild Projects:
QSM200UPEMPI QSM200UPNAPI QSM200UPWFPI QSM200EPNAPI QSM200EPWFPI QSM200EPEMPI

Vaild CUST_NAME:
STD STD_PERF DBG DEB DEB_PERF
```

# buildconfig 配置示例

**ProjectRev** 理论上可自定义，但必须与 modem 版本保持一致；标准版本 `CustName` 必须使用 `STD`。命令建议按多行方式书写，避免一整串过长。

## M1 / QSM200U 示例

```bash
# eMMC / 当前 M1-L1 实测配置
buildconfig \
  QSM200UPEMPI \
  QSM200UPEMNARL1A01_BL01BP01K0M01V01_LP5.15.153.01.001_V01 \
  STD

# NA 版本示例
buildconfig \
  QSM200UPNAPI \
  QSM200UPNANARL1A01_BL01BP10K0M01_QPEA_LP5.15.153.01.001_V01 \
  STD

# WiFi-only 版本示例
buildconfig \
  QSM200UPWFPI \
  QSM200UPWFNARL1A01_BL01BP10K0M01_QPEA_LP5.15.153.01.001_V01 \
  STD
```

## L1 / QSM200E 示例

```bash
# NA 版本示例
buildconfig \
  QSM200EPNAPI \
  QSM200EPNADARL1A01_BL01BP10K0M01_QPEA_LP5.15.153.01.001_V01 \
  STD

# WiFi-only 版本示例
buildconfig \
  QSM200EPWFPI \
  QSM200EPWFDARL1A01_BL01BP10K0M01_QPEA_LP5.15.153.01.001_V01 \
  STD

# eMMC 版本示例
buildconfig \
  QSM200EPEMPI \
  QSM200EPEMDARL1A01_BL01BP10K0M01_QPEA_LP5.15.153.01.001_V01 \
  STD
```

# 当前 M1 / L1 配置对比

本节把 QSM200U 当前实测配置与 QSM200E 对应平台配置放在一起对比。QSM200U 列为本次实际验证的 M1/L1 配置；QSM200E 列为同仓库脚本提示的 E 平台对应示例，ProjectRev 仍需按实际 modem 版本确认。

| **字段** | **M1 / QSM200U** | **L1 / QSM200E** | **说明** |
| --- | --- | --- | --- |
| ProjectName | `QSM200UPEMPI` | `QSM200EPEMPI` | 两平台 eMMC 示例项目名 |
| ProjectRev | `QSM200UPEMNARL1A01_BL01BP01K0M01V01_LP5.15.153.01.001_V01` | `QSM200EPEMDARL1A01_BL01BP10K0M01_QPEA_LP5.15.153.01.001_V01` | 需与 modem 版本保持一致 |
| CustomName | `STD` | `STD` | 标准版本使用 STD |
| Chipset | `SM6115` | `QCM2290` | 分别对应 200U / 200E 平台 |
| MACHINE | `sm6115-mtp` | `qcm2290-mtp` | Yocto 机器配置 |
| DISTRO | `qti-distro-fullstack-debug` | `qti-distro-fullstack-debug` | 常规 STD 构建默认值 |
| 构建入口 | `build_200u.sh` | `build_206e.sh` | 由 buildconfig 按 ProjectName 自动分流 |
| BP / Boot 平台 | `Kamorta` / `KamortaPkg` | `Agatti` / `AgattiPkg` | Boot/固件路径不要混用 |

配置成功后，终端会切到 `build-qti-distro-fullstack-debug` 编译目录，并显示如下关键信息：

```plaintext
DISTRO     = qti-distro-fullstack-debug
MACHINE    = sm6115-mtp
Supported image targets are:
qti-robotics-image

Current QUECTEL_PROJECT_NAME = QSM200UPEMPI
Current QUECTEL_PROJECT_REV  = QSM200UPEMNARL1A01_BL01BP01K0M01V01_LP5.15.153.01.001_V01
Current QUECTEL_CUSTOM_NAME  = STD
Current QUECTEL_CHIPSET_SUBTARGET  = SM6115
CUSTOM_BVERSION : QSM200UPEMNARL1A01
CUSTOM_SVERSION : BL01BP01K0M01V01
CUSTOM_VERSION  : 01.001V01
CUSTOM_QAPSUB   : V01
```

# AP 侧整编

**步骤二：** 执行如下命令进行 AP 侧整编：

```bash
buildall
```

该过程耗时较长，通常需要 1~2 小时。编译完成后，如果 `bitbake` 输出 `all succeeded`，表示 AP 侧镜像构建成功。

```plaintext
NOTE: Tasks Summary: Attempted ... tasks of which ... didn't need to be rerun and all succeeded.
```

# 一键打包

**步骤三：** AP 镜像编译完成后，执行如下命令生成 QFIL 烧录包、OTA 包以及调试镜像目录：

```bash
buildpackage
```

当前 QSM200U / `QSM200UPEMPI` 实测 `buildpackage` 返回 0，关键日志如下：

```plaintext
build full qfil success >>>>>>>>>>>>>>>>>>>>>>
UnPacking SUCCESS
TARGET_DEBUG_IMG_DIR: /home/soren/QuecPi/SC200/Linux_BL01_R010/quectel_build/fw/QSM200UPEMNARL1A01_BL01BP01K0M01V01_LP5.15.153.01.001_V01_debugimg
=============== debugimg copy done ===============
```

打包完成后，镜像会输出到 `quectel_build/fw/` 目录下。当前版本对应的主要目录如下：

| **目录** | **用途** |
| --- | --- |
| `QSM200UPEMNARL1A01_BL01BP01K0M01V01_LP5.15.153.01.001_V01` | QFIL 完整烧录包 |
| `QSM200UPEMNARL1A01_BL01BP01K0M01V01_LP5.15.153.01.001_V01_ota` | OTA 包，包含 `full_update_ext4.zip` 和 `target-files-ext4.zip` |
| `QSM200UPEMNARL1A01_BL01BP01K0M01V01_LP5.15.153.01.001_V01_debug` | 调试符号目录，主要保存 `elf` 文件 |
| `QSM200UPEMNARL1A01_BL01BP01K0M01V01_LP5.15.153.01.001_V01_debugimg` | 调试镜像目录，包含 `boot.img`、`dtbo.img`、`system.img` 等 |

# 镜像文件说明

QFIL 完整烧录包目录中包含烧录所需的主要镜像和配置文件：

**烧录配置文件：**`rawprogram_unsparse0.xml`、`patch0.xml`、`partition.xml`、`gpt_main0.bin`、`gpt_backup0.bin`。

**AP 侧镜像：**`boot.img`、`dtbo.img`、`system_*.img`、`userdata_*.img`、`vendor_*.img` 等。

**Modem / 固件镜像：**`NON-HLOS.bin`、`abl.elf`、`rpm.mbn`、`tz.mbn`、`devcfg.mbn`、`dspso.bin` 等。